Document processing
- General
- Comparison printing via MS Word with printing via XML
- Creating document modules
- Document variables
- Dynamic data fields
- Macros
- Methods
- Sequence control (IF condition)
- Conditional documents
- List definition
- Main document
- Testing the document
- Troubleshooting
Annex
General
Documents are the template for the print output from ClassiX® , whereby the generated documents can of course also be saved or sent by email/fax. As a rule, documents consist of document modules with stored Word documents. In exceptional cases for label printing, it may be that only one module (Word document) is required for printing, which is then integrated directly in the document and, for example, also specifies the dimensions. In the following, however, only the printing of documents such as offers, orders, etc. is considered.
Comparison printing via MS Word with printing via XML
There are currently two printing methods, printing via MS Word and printing via XML. This section gives a first overview of how the printing methods work and their advantages and disadvantages. A more detailed description is given below.
In general, printing via MS Word can be described as follows. At the beginning of the printing process, an empty Word document is created. Subsequently, the document modules assigned to the document are successively inserted into the generated empty Word document. The type or the sequence of blocks defines when and where the blocks are inserted. For example, the type "Footer" creates the footer of the document. The result is that the initially empty Word document is filled with content and can now be printed, saved, etc.
When printing via XML, a template is stored behind the document. This specifies the layout of the printout. This can be done on the one hand by referring to the document modules to be used, but the content can also be stored directly in the template. For example, a reference can be made in the footer of the template that the document module is to be dragged to print the footer or the content can be stored directly in the footer of the template. When printing, the layout is dragged and evaluated (memorised), thereby setting the contents of all placeholders (document variables). The template is a Word XML document which is only converted into a Word document as a COM object after preparation.
Printing via Word | Printing via XML | |
---|---|---|
System requirements | Any MS Office | from MS Office 2010 |
Performance | Slowly, because there is permanent communication between ClassiX and MS-Office. | Very fast, that the print preparation is done exclusively via XML. |
Stability | Moderate, COM errors may occur because Word must run parallel to printing and is constantly communicating between Word and ClassiX. | Good, because the preparation of the print is (almost) exclusively done by ClassiX. |
Functionality | Good, documents can be designed as desired. | Very good, because the template can be designed as desired. |
Create a new document for XML printing
This section shows an example of how to create a new document for printing delivery notes.
Creating a document
The first step in creating a new document is to create the document itself. In this example, the document is given the number "SDN" and the name "Delivery note". The area "Sales" is defined in the application area and the restriction can be used to set that the document is only valid for delivery notes (class CX_DELIVERY_NOTE).
Creating the template
The decisive step is now the creation of the template. The template is saved as a Word document in the directory "CX_ROOTDIR\appswh\data\Template\Forms\CX_PROJECT_NAME" under the name of the document, in this case defaultTemplate.doc.
The template could look something like this. It has a header and a footer with corresponding document variables, which are described in the same way. It also has two section changes and further document variables.
However, there are also a few hidden document variables. If you insert a few line breaks before the first section break, you will see that the document has a different header on the following page. The same applies to the two sections defined by the section breaks.
The document variables, which are described in the next table, ensure that the content is read from the document modules defined in the document and inserted at the appropriate place. Alternatively, the content could also be inserted directly into the template as described above. Thus, one could remove the document variable "call(XMLPrintListHeader)" for inserting the building block of the list header and define the list header here directly, as the following image shows.
Document variable | Description |
---|---|
call(XMLPrintPageHeaderFirstPage) | The block "Header" is inserted. If this is conditional, the condition is evaluated with regard to "first page". |
call(XMLPrintPageHeaderFollowingPages) | The block "Header" is inserted. If this is conditional, the condition is evaluated with regard to "next page". |
call(XMLPrintPageFooterFirstPage) | The module "footer" is inserted. If this is conditional, the condition regarding "first page" is evaluated: print.counter=11111 |
call(XMLPrintPageFooterFollowingPages) | The module "Footer" is inserted. If this is conditional, the condition regarding "next page" is evaluated: print.counter=99999 |
call(XMLPrintPageFooterLastPage) | The module "Footer" is inserted on the last page. If this is conditional, the condition regarding the "last page" is evaluated: last.printPage=1
Conditional modules can then be defined in the footer module:
|
call(XMLPrintDocumentHeader) | The block "Document header + header (next page)" is created. This is usually conditional. The condition is evaluated with regard to the "first page". |
call(XMLPrintDocumentFooter) | The block "Document footer" is inserted. |
call(XMLPrintListHeader) | The block "List header" is inserted. |
call(XMLPrintListItems) | The block "List position" is inserted for each position. |
call(XMLPrintListFooter) | The block "List footer" is inserted. |
call(XMLPrintComponentsBeforeListItems) | All other building blocks such as those of the type "Conditions" or "Free building block" are inserted, which are listed in the order of the building blocks in the document before the position list (type "List header" or "List position"). If there are several modules, they are inserted in the order in which they were sorted in the document. |
call(XMLPrintComponentsAfterListItems) | All other components, such as those of the type "Conditions" or "Free component", which are listed in the order of the components in the document after the item list (type "List header" or "List item"), are inserted. If there are several modules, they are inserted in the order in which they were sorted in the document. |
However, it is also possible to insert content into the template without using document modules. This is even much easier, but does not offer the possibility of encapsulating modules and using them several times. It is easier because you can insert the content directly in the template. For example, it would be conceivable to insert the list header of the position list directly in the header of the template instead of the document variable "call(XMLPrintListHeader)". The same applies to the document header, footer and so on. And although you do not go via the document modules in this case, document variables can still be used as placeholders for inserting ClassiX data, such as "uniqueID" for inserting the document number.
Document modules
Document modules are used to manage Word documents that are inserted into the template. The documents must be assigned an ID, which must be unique so that the documents can be exported and imported. It is advisable to name the modules like the document into which they are to be inserted, supplemented by an abbreviation describing the type. It could also be a consecutive number, but then the ID would not be meaningful. The following extensions have been established using the example of the document "SDN".
ID | Description |
---|---|
SDN_DH | Document header |
SDN_DF | Document footer |
SDN_LH | List header |
SDN_LI | List item |
SDN_LF | List footer |
SDN_CO | Condition (Condition) |
The type of the document module controls which task the module fulfils and where it is to be inserted. Thus, the module "list header" is inserted at all the places in the template where the document variable "call(XMLPrintListHeader)" has been defined.
The Word document can be stored conditionally in the document modules. These can be fixed conditions, such as whether the module "Header" is to be inserted on the first page or on the following page. However, the conditions can also be formulated depending on general system information (e.g. query regarding the logged-in client) or data of the document to be printed (e.g. query regarding the order type), etc.
Variable | Description |
---|---|
print.counter = 11111 | First page |
print.counter = 99999 | Next page |
last.printPage = 1 | Last page, this check is only available if a distinction is made in the template between the procedures XMLPrintPageFooterLastPage and XMLPrintPageFooterFollowingPages. A corresponding example can be found above with the XML document variables. |
var(cyberEnterprise).uniqueID = "001 | Query regarding the registered client (in this case if the registered client has the ID "001") |
type(this)=CX_PURCHASE_ORDER | Query regarding the document type (in this case, whether a purchase order is being printed.) |
The "document header" module has a special feature, which is usually always conditional. There is a condition for the first page ("print.counter=11111"). The document that was stored here is output as the document header. The Word document behind the condition for the next page ("print.counter=99999"), on the other hand, is used for the header of the next page. The advantage is that despite a uniform header across all documents on the first page, an individual document header can be set up on the following pages without the need for a document.
In addition to the Word document, the module can also define options such as "new page before the module". However, these options are only valid for blocks of the type "list position" or "list groups" as well as the blocks which are freely inserted before or after the list.
Document variables
In the MS-Word Editor the layout design for the document header can be created. If you have no experience in using MS-Word with dynamic data fields, it is recommended to first create a static layout design by defining the formatting of tables, fonts and inserted graphics (see above figure).
Dynamic data fields
As soon as the layout design is complete, the static information (e.g. name, first name, contact person, date, etc.) can be replaced by dynamic field variables. Select the field (e.g. name) and choose from the MS Word menu: "Insert"->"Field...". In the category: "Document automation" you will find the field name: "DocVariable". Select this field name and add the variable name (e.g. "DOCVARIABLE customer.partner.name"). If the inserted field names appear in an unusual form in the MS Word document, the field functions can be switched on or off via ALT + F9.
This method can now be applied to all fields visible in the MS-Word document. This may also include the sender address in the company header (e.g. in the case of different distribution centres).
Connecting with ClassiX® macros
Instead of referring to the variable name, ClassiX® macros can also be called. The call is made via the method "Call".
Using methods of the ClassiX® objects
It is also possible to call object methods from Word. For this purpose, the ClassiX® object is inserted as described above. The access to the object method is then done according to the C++ convention. The transfer of parameters is possible.
Sequence control via IF instruction
Word offers the possibility to control the process via branching. This is done with the IF instruction. This is inserted via the menu Insert/Field and by selecting the field name IF in the category Document Automation. The entry { IF } is inserted. The instruction must now be filled with the condition and the instructions for the two cases true and false.
The entry
is to be changed to
The inverted commas next to the statement are important. These encapsulate the statement.
Conditional document
In this example "Print delivery note" a simple document has been created which therefore only exists in a single form. ClassiX® offers the possibility to display the documents "conditionally". As an easy to understand example, the case assumption is used, that from a certain date (e.g. 01. Jan. 2003) a new company logo with a new document header is valid. We now select the document module from the document module selection list and go into the editing mode. If the content selection box is set from "Simple document" to "Conditional document", the content can now be transferred to the conditional document module.
The document module window has now changed its design. Instead of a preview of the OLE object you can now see the different selection conditions. Using the right mouse button, you can now add another condition or remove a selected condition.
For the example, the formatting from the Word document can now either be saved locally or copied to the clipboard. A new condition can be created with the right mouse button.
The conditions are worked through in sequence from top to bottom. If a condition is fulfilled, the comparison is aborted. It is therefore not necessary to enter an Else condition for the alternative document header. Using the keys and the order of the conditions can be changed.
For the second condition, the content of the clipboard can now be pasted into the new document and changed according to your own wishes (e.g. different logo, different letterbox etc.).
The next step in the example "Print delivery note" should now be The document header for the following pages (document header 2nd page) should be defined. And the document footer (main page and following pages)
Since the layout of modules often differs depending on the number of pages, the following standard conditions were added to ClassiX®:
- Insert (condition for first page)
- Insert (condition for next page)
- Insert (list header for the beginning of the list)
- Insert (list header 2nd page for lists larger than one page)
For example, a list that is spread over several pages will have a detailed list header on the first page and a shortened version on the following pages where the list is continued.
For examples of creating conditions, refer to the document"Printing Receipts".
Lists can be switched off:
- List group
- List header
- List position
- List footer
- List transfer top
- List transfer below
exist. The procedure for creating a list document module is no different from that for the other modules. The difference lies in the formatting of the displayed data. While the document modules (header, footer, etc.) all have a fixed position in the document layout, the display of the list positions depends on the space available for them and distributes positions that are not displayed to the following pages.
Combining the blocks into one document.
Once all the necessary document modules for the desired result have been created, they can be combined into a main document.
New documents can be created via the menu item "Basic data"->"Documents"->"Document". Documents have an id that can be freely assigned, a document type (for which work group this document applies, e.g. sales or purchasing) and a document description. Here, too, the name can be entered in several languages. For the example (delivery note printout) we use the document type Sales.
For the main document, a fixed layout can be specified, which can be adjusted via the margins (top, bottom, left, right). For the example (delivery note print) we enter a standard dimension (left: 25mm, top: 10mm right: 0mm bottom: 5mm).
Using the "Insert" and "Remove" buttons, the required document modules can now be conveniently added. The blocks contained in a document are processed sequentially from top to bottom. The sequence of the blocks can be changed via the buttons and can be changed.
Via the button the inserted modules can be displayed in a tree structure. The tree structure is helpful if document modules contain further sub-document modules.
Testing (using) the document
In order to view the example document as a whole, we go to the main menu item "Activities->Sales->Delivery note" or and call up an existing delivery note(if no delivery note existsyet, one must be created)
Continue via the print dialogue (with OLE in the foreground). To view the document you can add or omit the following options:
- Print cover letter
- Print footer text
- Print conditions
These three options offer an exception in the program logic of document printing. It is also possible to implement this additional information via a further document module. Since this option is available for all processes, it was integrated into the dialogue. The language can also be set in the print selection dialogue. And there is the option to archive the document in different ways.
The document can be previewed using the "Preview" button. The preview tool offers the possibility of scaling and page navigation. Changes to the layout can now be made to the document modules. Further blocks can be added or superfluous ones removed.
Troubleshooting + (Tips & Tricks)
Due to the interaction of the software with OLE objects, ClassiX® is not immune to the peculiarities of Microsoft Word. In the separate document:"Troubleshooting OLE Objects", the known peculiarities and possibilities to circumvent them are listed.